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DESIGN STANDARDS 
FOR INSTRUCTIONAL COMPUTER PROGRAMS 



Introduction 

The NSF grant GZ-29B0» "Physical Processea Id Terrestrial and Aquatic 
Ecosystems/' is concerned with the development ot instructional units* called 
modules* which teach aspects of physical processes to students in the life 
sciences. Most modules contain computer programs which are built around a 
particular application of a physical process. The program design standards 
are aimed^t enhancing the usage* portability, ease of modification, and 
dissemination of these programs. In particulsrfi the programs are designed 
to be uniform in structure and usage* tolerant of student input, easy to use., 
and to operate in either batch or interactive moda and with easy re-directioa 
of input and output. All programs are coded in ANSI Fortran (with a few 
carefully isolated and well documented exceptions permitted) and closely 
follow the standards set by the CONDUIT organlzAtioD. 

Standard input and output modt.lcs are the principal agents for program 
standardization. All external input is handled by m module called the 
format free input system (Anderson and Gales* 1978) which permits a user to 
assign values to variables by name without regard to position or order. This 
system is easy to use, percits self-documenting input, offers helpful 
diagnostics (unlike most other input systems such as Fortran*! non-standard 
NAMELIST)* is suitable for all but very large data sets* and features a 
default value structure which permits a student to exercise a graduated 
degree of control over the program which expandi as his knowledge and skill 
increase. 

The output is handled by two modules called PRNTSD and PL0T3D (Gales 
1978a* 1978b). The former is e very flexible and portable printer plot 



4 



2 



package \ .C' ites point, nulti*line. And iinulated three-dimensional 

surface r< ^s suitable for the display of many physical processes, 

while the It ■\ less portable three-dioensional hidden line Calcoop* 

type display. ave similar interfaces to the calling program. 

Vith the input und output modules fixed, the only variable left is 
the computationa; 'iK>dule, and this is invoked by a main program, or driver 
routine, which rdinates its activities vith those of the input and output 
modules. 

Another agent of standardization is the approach offered by structured 
progrstmning (SP) which emphasizes simplified control paths, single purpose 
routines developed by step vise ref ine^nent, and single entry - single exit 
units vith veil defined interfaces. All of the programs are guided by 
the principles of SP and come of thea (including the three support modules) 
are coded in a literal structured Fortran vhich adheres ft^trictly to the 
half-dozen control structures of SP (Gales, 1975 and Appendix 3)» 
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Logical Structure of Programs 

To the user, each program appears as follows: 



in 


1, i, 


Program 








"■ * • • • 





where 1^ is the jth input data set and o^ is its associated set of Pm3D 

or PL0T31) displays. 

To a programmer, each program looks HVce this: 

aefault values for 



input variables 
declarations for 



Input variables 



Format 
Free^ 
Input 
System 



Input 
"values 



a* YjZ coordinates for 



points to be displayed 
plot titles 



MAIN 
PROGRAM 



COMPUTATIONAL 
MODULE 



plot 

directives 




where the solid lines indicate passage of information by way of files, and 
the dotted lines indicate connnuntcation via conunon blocks. All files are 
formatted except for the file of x.y.z coordinates which is in binary. 

The »ain pxogra». which coordinates the activities of the input, output 
and computational modules, consists of an initialization section, a read- 
p.ocess-output loop, and a termination section, and is structured a. follows 



e 



Initialization 



NODFLT - .T.? 



Ycc 



No 



Read default values for all variables 
from a built-in default file 



Prompt a user with a message which re- 
quests input; read in the next user- 
supplied data set 





r 

FINIS ' 


"\ 

• .T.? 


Yes 










No 




Check for errors in the 
input 8^,t just read 



Prompt the uaer with 
a tenninacioit message; 
terminate proj^ram 



output 


Ves f 


appropriate 


error 


( 


messages 





L. 



were errors found? 



No 



call a computational routine which generates 
sets of-x, y, z coordinates for the display or 
displays which represent a physical process 

— — : — I 



Yes 



^were errors found^ 
which escaped the 





No 


Write out the x,y,z pJ 
to a binary file; writ 
a formncteci file 


Lotting coordinates on- 
:e the plot titles onto 





call the PLOTJD or PRNTJD subroutines which 




plot - the data 
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The variables NODFLT and FINIS are standard input variables which are used 
to suppress the input of default values^ and to terminate every program, 
rospco t ivoly . The main program always calls six special purpose routines: 
/ NMLIST - a small routine which writes a formatted file containing tne 
names, dimensions, and types of all input variables. 
QQREAD - a routine in the fomat free input syatcm which handles 
input . 

WRTDFF - a small routine which writes out default values for all 

input variables' on a formatced file to be read by QQREAD. 

WRTTLF - a small routine which writes out a set of titles for 
PRNT3D or PL0T3D on a formatted file. 

WRTXYF - a small routine which writes x,y,2 coordinates onto a 

binary file for use by PRNT3D or PL0T3D. 

QQPR3D - errry points in PRNT3D or PL0T3D. 

or 
QQPL3D 

Physical Structure of Programs 

The physical structure of a program, i.e., the choice of identifiers, 
size and format of routines, file structures and formats, subroutine 
linkages, etc., should^ref lect its logical organization. 

Identifiers are 1-6 character narce assigned to values, common blocks, 
programs, subroutines, functions, and files. Identifieru should 

• be as few as possible 

• have a single meaning which remainn invariant throughout 
a routine 

• correspond to some reality outside the program; i.e., 
should represent a part, process, or concept associated 
with the problem , not the program 

• pofrses^*^ mneaonic significance 
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The choice of Indenc^.fler names is important because they govern the read- 
ability of code laore than any other single factor. A well vnritten prograa 
has very few identifiers with changing or multiple meanings; their presensc • 
in large numbers is a sure sign of a poorly structu.:ed and overpatched 
program with many unstated limitations and under :ted bugs. 

Each routine should consist of a header and a body . The header con- 
tains declarations and conanents and primarily defines what is being operated 
on. The body consists of executable code and defines the operations to be 
applied to the data described in the header. The body should be fairly 
small (about one page), should perform a single basic purpose, should be 
entered at the top and exited at the bottom, and should have relatively 
tew, but well defined, connections to other routines. 

The header provides the maiii internal documentation for the. program, 
serves as a checklist against which code can be compared, and discourages 
poorly written code. One cannot easily graft a good header onto bad code, 
because the many variables with their changing meanings and non-mnemonic 
spellings cannot be declared and defined in the header in a compact and 
understandable way. It is essential that the header and body evolve 
together, with the header serving as a censor of bad design. Since the 
header reflects the code> cumbersome and difficult headers arise only 

from poorly written code. 

The hcjder for the main program consists of a number of sections ejvh 

^ 

of which is delimited by vertical blank apaces and a line of dashes. 
The sections are as follows: 
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Purpose - a brief description of the purpose of the prograc including 
the main execution steps in order of occurrence. 

Identification - an identification number, date^ locationt language, 
computer installation, and programmer name(s). 

Global variables - a group of common Mocks each structured as follows 
descriptive cooasents enclosed in a star box, the comnon 
block, explicit type declarations for all of its variables, 
and comment caids which define all variables. 

Local variables - explicic type declarations and definitions for all 
local variables* 

Functions - explicit type declarations avtd definitions for all but 
standard ANSI intrinsic and external func::ion5. 

Subroutines * names of all subroutines called by this routine. 

Externals - tlie names,' purposes, and algorithms for all subroutines 

and functions which are unavailable or are coded in machine- 
dependent language • 

Files - the names, types (formatted or binary), direction (input, 
output, input/output), and data items for all files ured 
in the program. 

Restrictions - a list of limitations. 

Error Handling - a list of error conditions and actions. 
Non-ANSI Usage - a list of non-ANSI usages. 
Machine Dependencies - a list of machine dependent fe.iturt's, 
e.g. word length dependencies. 

t 

Constants - a set of DATA statements which assign values to all 
constants in the routine. 
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Inltlallration - a set of assignments and loops which explicitly 
initialize all variables which require starting values. 

Start - the start of the body of nhe routine. 
A complete fons for the header is presented in Appendix I. 

Subroutines and functions contain linkages, headers, and bodies. 
Subroutine linkages are structured as follows. The arguments are separated 
into three class':s: input , inpu t/output , and output arguments. The input 
arguments are listed first, the input/cutput arguments are listed next and 
arc separated from the input arguments by several spaces, and the output 
arguments are listed last, and are separated from the input or input/output 
list by several spaces. For example, 

SUBROUTINE SUBl (X,Y, FX, ^BOT),- 

input input/ output 
output 



SUBROUTINE SUB2 ( vlv^Sli' 

input/ 
output 



SUBROUTINE SUB3 (X,TOT, ^^i^ 
Inpi't output 

Such a convention clearly reveals the nature of the linkages. The con- 
vention also applies to those statements which i.all the subroutines, for 
example, CALL SUB3 (X,TOf, B,ZR) . All the arKuments for 

functions should be input arguments only. 

The headers for subroucines and functions differ slightly from the 
main program header, in that theS*: 
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• have £n "Argumcntt'* section 

• lack an ••Identltlcatloa", aecdin (unless le differs froa 
the main program) ' 

. • lack discriptive comments and definitions for common bJock 
variables; and unused variables in the common block are 
declared with a 2ZZZA (*) convention 

• lack a "Files*' section 
End-of-fi3e Handling 

The end-of-f ilc mark*r, whouc full treatment is undefined in AHSI 
Fortran, ic needed to delimit input data sets rexd by the fcrt^at free 
inpuc system, and to terminate files of x,y,z coordinates. In the ^oraer 
case, the ena-of-file is repretsented by a dollar sign ($), and In the 
latter case by the x,y,z triple (-99999., -99999., -99999.) 
Error Handling f 

In most cases, errors which arise or are detected within a subroutine 
are handled aa follows: 

1) the error condition triggers s message of the fom: * A 

******ERKOR NO. n DETECTED IN name ' 
<error me8sage> 

s <the names snd values of vavinbles which 

closely relatf) to the crror> 

where n is the error number snd name is rhe name cf the sub<» 

routine^ The error message is written out on s apecisl error 

message file, although the latter may be equated to the 

itandard output file. 

2) the error number is pssaed bsck to the calling routine vis 
coxnaon or sn argument list. 

12 
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3) the subroutine is aborted and control returns (through various 
subroutine levels if necessary) to the main prograa. 

4) thfi nain program teros out all error indicators and skips to 
the next input d/ita set. 

The above procedure permits the processing and error scanning of multiple 
sets of input when the program is run in batch xaode, and insures easy 
recovery from errors by the user when the program Is run Interactively. 
Input 

All external input is handled by the format free input system which 
automatically checks for name» value» and subscript violations. Each 
program also contains a special subroutine, named INCHK, which tests 
each input variable v against a range, vMlN to vHAX, or set of permissablc 
values. Values outsids this range trigger error messages. The vMIN and 
vMAJC values are set by data statements within IMCHK. 
Output 

All output is designed to fit on standard Sh by 11 inch pages for 
easy storage and dissemenation. The output consists of prompter messages, 
echoed input, error messages, and the plotted output from PRKT3D or PL0T3D 
along with their associated titles and other annotation. 
External Documentation 

Each instructional module is presented as a package which is described 
by the following packing list: 
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IMP07;TANT 



Packing List for: progrEa <nainc> 



Enclbsed with this list are the following elements conprising the package: 
1 each — Magnetic tape containing a) the source progran plus support 

routines, and b) sample runs with annotated control cards 

and input cards. 

1 each — CONDUIT Tape Distribution Form describing how the tape was 

recorded and what it contains. This form contains essential 

information and should be carefully read. 
1 each — Listing of the tape as read by us before we sent it. 
1 each — Listing of the source program plus support routines as compiled 

under the Minnesota Fortran ANSI verifier compiler. 
1 each Module description plus problem sets, program abstrixt. and 

user's guide. 
1 each — Design Standards for Pvograas. 

1 each ~ Program abstract, user's guides, and programmer's guides for 

all support routines. 
1 each — Notes for implementers. 
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The user's guide consists of the follc.:/i;n^ sections: 

1) Identification - contains name, author, date^ and location 

2) Purpose 

3) Operation 

4) Program organization - an aggregate flow chart of the program 

5) Input - a table of all input variables with their names, types, 
dimensions, range limits, purpose, and default values 

6) Output - a verbal discussion of the output produced by the 
program 

7) Restrictions 

8) Error messages 

9) Sample runs * a complete input set Including annotated c^trol 
cards and an annotated set of input data sets, followed' by the 
exact outputs which result. The sample run should permit users 
at a different in&tallation to test the program. 

10) References 

The programmer's guide for each of the Physical Processes computer 
modules consists of a note to implementers. Internal comments in the computer 
program, and this document on design standards* The three support routines 
FFORM, PRNT3D, and PL0T3D, however, which handle Input/output for each 
module, have detailed programmer's guides as separate documents* 
Testing Procedures 

Testing procedures should insure that all subscripts remain within array 
bounds, all control paths are fully exercised, all boundary conditions ara 
tested, and all procedures are numerically seabla* 
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APPENDIX I: FORfiAT OF PROGRAM HEADERS 

The header should be formatted as follows: 
card columns 

1 6 7 21 29 37 45 53 61 

C 
C 

C-PURPOSE 

C 

C comments describing the purpose and main execution stepa 

C 



C 

c 

C-IDENTIFICATIOK 

C 

C I.D. number, date, location, language, computer installation, 

C programmer name(s) 



C 
C 

C-GLOBAL VARIABLES • 

C 

Q ****************************************************** 

C * purpose and description of following common block * 

C * * 

Q ****************************************************** 



COHMON/name/ v. 



INTEGER V, V, v, . • . . 

' REAL V, V, V, • • • 

LOGICAL V, V, V, • • • 

C 

C DEFINITIONS 
C 

C V" verbal description of variable 

C V- 



C 
C 

C-LOCAL VARIABLES 



INTEGER V, V, v, • • • 

REAL V, V, V, • • • 

LOGICAL V, V, V, • • • 



If? 



APPENDIX I continued 
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1 6 7 21 29 37 45 53 61 

C DEFINITIONS 
C 

C v« verbal description of variable 

C v 



C 

C 

C . 

INTEGER fen, fen, fen, ... 

REAL fen, fen, fen, ... 

LOGICAL fen, fee, fen, ... 

C 

C DEFINITIONS 
C 

C fen- verbal deseription of purpose of funetton 

C fen- 



C 

C-SUBROUriNES 

C sub, sub, sub, 

C . 



C 

c 

c 

Q sub purpose, algorithm, and interface to rest 

Q of program for each subroutine or function 

C which is highly machine dependent or is not 

C included in the sourca deck 



c ; . 

c 

C £ the type (formatted or binary), direction 

C (in, out, or in/out), and data items 

C for file f 
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APPENDIX I contlnufid 



67 21 29 37 45 53 61 



C 
C 

C-RESTRICTIONS ~ 

C 

C A discussion of prograra limitations 



C 
C 

C-ERROR HANDLING 

C 

C A list of error conditions and actions 



C 
C 

C-NON-ANSI USAGES 

C 

C List of non-ANSI features 



C 
C 

C-MACKIWE DEPENDENCIES ' 

C 

C Diftcussion of the effects of such things as word lengths, 

C numerical precision, and memory requirements 



C 
C 

c 

DATA V, V, V / ... / 

C 
C 

C-INITIALI2ATI0N 

C . 

All variables which require starting values ara 
Initialized here* Also files may be rawuod 



c 
c 

C-START ■ ; 

C 

Th« bodjr oi thm prograa BCarCs h«r* 
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APPENDIX I continued 

Subroutines and functions differ from the main program in that they 
. have an arguments section and generally lack identification and files 
sections, often do not comment the common blocks, and specify unused common 
variables with the ZZZZn(*) t:onventioa. The first part of a subroutine 
header is as follows; 

1 6 7 21 29 37 «5 53 61 

SUBROUTINE name(a»a, a, a, a, a) 

C 
C 

C-PURPOSE 



C 
C 

c 

INTEGER a, a, a, 

REAL a» a» a, 

LOGICAL a» a» a, 
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APPENDIX II: ANSI FUNCTIONS 



Allowable Intrinsic Functions ; 

ABS lABS DABS 

AIKT INT IDINT 

AMOD MOD 

AHAXO AMAXI MAXO MAXI I»1AXI 

. AMINO AMINI , MINO MINI DMINI 

FLOAT IFIX 

SIGN ISICN DSIGN 

DIM IDIH 

SNGL REAL 

AIMAG DBLE CMPLX CONTG 



External functions: 

EXP DEXP CEXP 

ALOG DLOG CLOG 

ALOGIO DLOGIO 

SIN DSIN CSIN 

COS DCOS CCOS 

TANH SQRT DSQRT CSQRT 

ATAN DATAN ATANH DATANH 

DMOD CABS 
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APPES^DIX III: STRUCTURED FORTRAN 



Structured Fortran uses the faniliar control structures of SP: 



1. 



IF b THEN s ENI>-IP 



2. 



IF b THEN 8] ELSE 82 ENI>-ELSS 



3. 



IF bi THEN Bi ELSEIF b2 THEM Sj 



OTHERWISE s END*ELSEIF 
n 



4. WHILE b DO s END-WHILE 

5. REPEAT 8 UNTIL b END-REPEAT 

6. LOOP 8 WHILE b DO 8 END-LOOP 

7. DO 8 CONT/.NUE (a restricted repeat statement) 

where bf bj, denote Boolean expressions and 8» 8] 9 denote any 
set of statements Including other control structuires. The above 
structures are translated into left and right hand sides in Fortran 88 
described belov. The translation introduces one non-ANSI feature which 
can easily be removed by a very small preprocessor* For a discussion 
of the use of this technique see Gales* 1975. The control structures are 
as follows; 
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II. Structure 



1 67 21 25 





IF 


. (.NOT.( 


b 


^ ^ GOTO 101 • 


THFW 




8 


101 CONTINUE: 






TT? 


( NOT ( 


u 


.))GOT0201; 


THEN 




fil 


GOTO2025 


ELSE 


201 


82 


202 CONTINUE; 


END-ELSE 




IF 


.(.NOT.( 


bl 


.))GOr030I; 


THEN ■ ' 




8l 


CnT0307; 


ELSEIF 




K9 
D4 


^ ^GTlTO'^n? 






• 




• 

FLScIF 


30J IF (.NOT.( 


b6 


.))COT0306; 


THEN 




86 


GOTO307; 


OTHERWISE 


306 


«7 


307 CONTINUE; 


END-ELSi:iF 


C 


WHILE 


^01 IF (.NOT.( 


b 


O)CX)T0402; 


DO 




• 


GOT0401; 


END-WHILE 


A 02 CONTI^HTE 






DO 701 I-l^N 




» 


701 


CONTINUE 
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XI. 



St rue Cure (continued) 



17 21 25 



c 


REPEAT 


301 


8 . 


c 


UNTIL 


IF (.NOT.( 


b 


•))COT0501; 


END-REPEAT 


C 


LOOP 


601 


• I 


C 


WHILE 


IF (.NOT.( 


b 


.))GOTO602; 


DO 






GOT0601; 


END-LOOP 


602 CONTINUE 
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